\documentclass[a4paper,11pt]{article}

\usepackage{epic,eepic,enumerate,amsfonts,amssymb,amsmath}
\usepackage[portuguese]{babel}
\usepackage[noline,ruled,linesnumbered,portugues]{algorithm2e}
\usepackage{fullpage,setspace}
\usepackage{graphicx}   % need for figures
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}%%Hifena corretamente palavras acentuadas
\usepackage{natbib}
\usepackage{tikz}
%\usetikzlibrary{positioning}
\usepackage{makeidx}
\usepackage{indentfirst}
\usepackage[pdftex]{hyperref}
\usepackage{listings}
\title{Manual do Usuário - Tira-Teima}
\author{Universidade de Brasília}
\setlength{\parskip}{0.2cm}
%\onehalfspacing

\makeindex

\begin{document}

\maketitle
\newpage
\thispagestyle{empty}\tableofcontents
\newpage
\section{Introdução}

Este documento descreve os procedimentos de configuração e uso da ferramenta Tira-Teima, incluindo a sintaxe de seus arquivos de comandos. Este documento não descreve detalhes de arquitetura e implementação do projeto Tira-Teima, sendo necessário consultar a documentação específica, disponível gratuitamente em \url{http://code.google.com/p/tira-teima/}. % como a sintaxe de seus arquivos de comandos., bem como o código fonte do Tira-Teima.
Esta documentação é destinada a qualquer professor, instrutor ou aluno que deseje utilizar o Tira-Teima na elaboração de tutoriais e/ou na simulação de algoritmos simples.

\subsection{O Projeto Tira-Teima}

O Tira-Teima é um visualizador de algoritmos interativo que permite ao usuário executar o código passo a passo e verificar o valor das variáveis e dos arquivos em cada passo. Foi projetado para auxiliar no ensino de disciplinas introdutórias de computação, como Computação Básica ou Introdução à Ciência da Computação. O Tira-Teima lê um arquivo de comandos, chamado de \textit{roteiro}, que geram a visualização desejada. %É planejado, no entanto, para futuras versões, que esses comandos possam ser gerados automaticamente a partir de um programa escrito em uma linguagem de programação convencional, como C ou Pascal.
A Figura \ref{fig:tirateima} abaixo ilustra a interface do Tira-Teima com a execução de um programa. O ambiente possui seções de visualização de código fonte, variáveis, arquivos e console.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=15cm]{img/tirateima}

\caption{Interface do Tira-Teima.}
\label{fig:tirateima}
\end{center}
\end{figure}

\section{Configuração e Execução do Tira-Teima}
\label{sec:config}

O Tira-Teima foi desenvolvido na plataforma Java e, portanto, requer que a JRE (\textit{Java Runtime Enviroment}) esteja instalada no sistema. Para executar o Tira-Teima, é preciso ter a versão 1.5 ou superior da JRE. Além disso, é recomendado um mínimo de 128 MB de memória livre. % para rodar o sistema.
O Tira-Teima foi projetado para executar tanto como uma aplicação quanto como uma \textit{Applet}. Na biblioteca do Tira-Teima (\textit{tirateima.jar}) estão disponibilizadas classes para esses dois modos de execução.
Em qualquer um dos modos de execução, o Tira-Teima espera receber como parâmetros os nomes de dois arquivos: um arquivo de código fonte e um arquivo de comandos.
O arquivo de código fonte pode estar escrito em qualquer linguagem de programação, no entanto, o Tira-Teima oferece apenas suporte ao \textit{highlighting} das linguagens C e Pascal. %O arquivo de comandos contém as instruções para gerar a visualização. A estrutura e sintaxe desse arquivo é descrita nas seções seguintes.

\subsection{Executando o Tira-Teima como uma aplicação}

Para executar o Tira-Teima localmente como uma aplicação basta utilizar o arquivo \textit{.jar} como uma aplicação Java, usando a JRE. É possível também executá-lo pelo terminal do sistema, por meio do seguinte comando:

\textbf{java –jar <caminho para o ``tirateima.jar''>}

Alternativamente, pode-se acessar explicitamente a classe que executa o Tira-Teima como uma aplicação. Assumindo-se que o jar do Tira-Teima foi adicionado ao classpath, pode-se fazer:

\textbf{java tirateima.main.Programa}

Ou, ainda:

\textbf{java –classpath tirateima.jar tirateima.main.Programa}

Nos procedimentos descritos anteriormente, nenhum parâmetro foi passado para o Tira-Teima. Se isso acontecer, o Tira-Teima vai abrir sem nenhum programa carregado e mostrará uma mensagem de advertência ao usuário. Para passar os parâmetros para o Tira-Teima, é preciso complementar o comando:

\textbf{java –jar tirateima.jar <arquivo de código fonte> <arquivo de comandos>}

Caso o algoritmo a ser visualizado acesse arquivos, é preciso que estes estejam no mesmo diretório do Tira-Teima. Mais detalhes sobre a utilização de arquivos podem ser encontrados na Seção \ref{sec:comandos} de comandos do Tira-Teima.

\subsection{Executando o Tira-Teima como uma \textit{Applet}}

Para executar como \textit{applet}, o Tira-Teima espera um parâmetro definindo o modo como a \textit{applet} será mostrada na tela, ou seja, (1) integrada ao navegador, (2) com uma janela própria, ou (3) escondida.
Quando integrada ao navegador, a \textit{applet} do Tira-Teima será executada como qualquer outra \textit{applet} Java, como um objeto na página.
No modo de janela, por sua vez, será criada uma janela separada que conterá a interface do Tira-Teima. Se a página que contém a \textit{applet} for fechada, a janela criada também será fechada. 
No modo escondido, nada será mostrado até que o método \textit{abrirEntrada} da \textit{applet} seja chamado, quando, então, uma nova janela será aberta. Esse último modo é bastante útil para controlar dinamicamente o Tira-Teima por meio de uma linguagem de \textit{script}, como o \textit{JavaScript}, por exemplo.
Para definir o modo de execução do Tira-Teima, é preciso passar um parâmetro, que pode assumir os seguintes valores:

\begin{itemize}
\item \textit{applet}: para o modo de \textit{applet} integrada ao navegador,
\item janela: para o modo de janela,
\item escondido: para o modo escondido.
\end{itemize}

No modo janela, pode-se ainda passar dois parâmetros adicionais: largura e altura, para definir as dimensões iniciais da janela aberta.
Além da definição do modo de execução, é preciso passar os nomes do arquivo fonte e do arquivo de comandos, por meio dos parâmetros <arq\_fonte> e <arq\_texto>, respectivamente. No caso da \textit{applet}, esses parâmetros são obrigatórios. O endereço dos arquivos de código fonte e de comandos devem ser relativos ao diretório onde está a página no servidor. Preferencialmente, esses arquivos devem estar no mesmo diretório que a página.
Se o Tira-Teima precisar acessar algum arquivo em modo de leitura, o arquivo em questão deve estar no mesmo diretório que a página.
Abaixo segue um exemplo de arquivo HTML que abre o Tira-Teima no modo de janela:

\begin{center}
	\lstset{language=Html,captionpos=b}
	\begin{lstlisting}[caption={HTML para abrir o Tira-Teima no modo de janela.},label={list:reasoner}]
<html>
    <head>
        <title>Tira-Teima</title>
    </head>
    <body>
        <applet archive="tirateima.jar" code="tirateima.main.Applet">
            <param name="modo" value="janela">
            <param name="arq_fonte" value="teste.pas">
            <param name="arq_texto" value="teste.txt">
        </applet>
    <body>
</html>
\end{lstlisting}
\end{center}

\subsection{Executando  o Tira-Teima como uma \textit{Applet} Escondida}

A classe \textit{tirateima.main.AppletEscondida} foi criada para o modo escondido da classe \textit{Applet}. Ela permite que a janela do Tira-Teima seja mostrada ao se clicar um botão, sem que haja necessidade de integrar à página código em \textit{JavaScript}.
Basicamente, a classe \textit{AppletEscondida} fica integrada ao navegador na forma de um botão que, quando apertado, ativa a janela do Tira-Teima. Para definir o texto que aparece no botão, basta definir o parâmetro nome.
Abaixo segue um exemplo de uso:

\begin{center}
	\lstset{language=Html,captionpos=b}
	\begin{lstlisting}[caption={HTML para abrir o Tira-Teima no modo escondido.},label={list:reasoner2}]
<html>
    <head>
        <title>Tira Teima</title>
    </head>
    <body>
        <applet
                archive="tirateima.jar"
                code="tirateima.main.AppletEscondida"
                width=120 height=40>
            <param name="arq_fonte" value="programa504.pas">
            <param name="arq_texto" value="roteiro504.txt">
            <param name="largura" value="800"> <!-- largura da janela -->
            <param name="altura" value="600"> <!-- altura da janela -->
            <param name="nome" value="Exemplo 504"> <!-- texto no botao -->
        </applet>
    </body>
</html>

\end{lstlisting}
\end{center}

\section{Criação de Roteiros para o Tira-Teima}
\label{sec:comandos}

O arquivo de comandos do Tira-Teima é um arquivo texto comum, chamado de \textit{roteiro}, com uma série de instruções para a visualização do programa na interface gráfica do Tira-Teima. As próximas subseções detalham a sintaxe definida para a criação de roteiros.
%cuja sintaxe será definida a seguir.

\subsection{Considerações Gerais}

Recomenda-se que o arquivo só use caracteres ASCII padrão. Caso seja necessário o uso de caracteres especiais, como os caracteres acentuados do português, o arquivo deve utilizar o charactere encoding padrão do sistema em que o Tira-Teima irá rodar.
Para fins de entendimento das regras a seguir, são feitas as seguintes definições:

\begin{itemize}
\item Um \textbf{identificador} ou nome é qualquer seqüência de letras, dígitos ou caractere de sublinhado ``\_'', iniciada por letra ou caractere de sublinhado.
\item Um \textbf{literal-caractere} (ou apenas caractere, quando não houver ambigüidade) é um caractere ou uma seqüência de escape entre aspas simples. O caractere não pode ser aspa simples, contra-barra ou quebra de linha. As seqüências de escape aceitas são listadas na Tabela 1.  As aspas não fazem parte do valor do literal-caractere. 
\item Uma \textbf{\textit{string}} é uma seqüência de caracteres entre aspas duplas. A seqüência não pode conter aspas duplas, contra-barras ou quebras de linha. As seqüências de escape aceitas são listadas na Tabela 1. As aspas não fazem parte do valor da \textit{string}.
\item Um \textbf{número inteiro} é qualquer seqüência de dígitos, com ou sem um sinal inicial. Os valores serão interpretados como números decimais.
\item Um \textbf{número real} é qualquer seqüência de zero ou mais dígitos, seguida de um ponto decimal e um ou mais dígitos. Adicionalmente, pode haver um sinal na frente do número e uma indicação de expoente na base dez na forma (e ou E)(número inteiro). Ex: +314.1592e-2.
\item Uma \textbf{constante} é uma \textit{string}, um caractere, um número inteiro ou um número real.
\end{itemize}


%\begin{tabular}{|c|c|}
%\hline \textbf{Seqüência de Escape} & \textbf{Caractere} \\
%\hline 
%\" & Aspa dupla (seqüência válida somente em \textit{strings}) \\ 
% \' & Aspa simples (seqüência válida somente em caracteres) \\ 
%\\ & Contra-barra \\ 
% \t & Tabulação \\ 
%\n & Nova linha \\ 
%\r & Retorno de Carro \\ 
%\hline 
%\end{tabular}

Ao final da explicação de cada comando, é mostrada uma expressão que resume a sintaxe do mesmo. Essas expressão segue as seguintes regras:

\begin{itemize}
\item Termos entre < e > devem ser substituídos por um valor correspondente, sem os sinais < e >.
\item Termos ou expressões entre colchetes ([ e ]) são opcionais e podem ou não ser substituídos.
\item Termos seguidos de … podem ser repetidos indefinidamente.
\item Todos os sinais de pontuação tais como vírgula, ponto-e-vírgula e ponto são obrigatórios, quando forem especificados. 
\end{itemize}

\subsection{Estrutura do Roteiro}

O Tira-Teima utiliza a noção de passo como a unidade básica de navegação do algoritmo. Cada passo é traduzido em um estado do Tira-Teima, ou seja, as mudanças na interface são realizadas entre dois passos consecutivos. Do ponto de vista do roteiro, um passo corresponde à um conjunto de um ou mais comandos. Se existir mais de um comando para um determinado passo, todos os comandos serão executados e será salvo somente o resultado dessa execução, sem que sejam vistas as modificações intermediárias entre os comandos. Isso é útil para simular funções e procedimentos complexos, sem que o usuário final veja os processos intermediários. Portanto, o roteiro do Tira-Teima é uma seqüência de passos que guiará o processo de visualização do algoritmo desejado. Para todas as regras abaixo, os espaços em branco e quebras de linha serão ignorados. %Além disso, o Tira-Teima não diferencia as maias palavras-chave são 

\subsubsection{Definindo Passos}

O Tira-Teima assume que cada passo do roteiro está relacionado a uma linha do programa original (código fonte), portanto, todos os passos são iniciados pelo número da linha que deve ser destacada no código fonte.
Para tornar o programa mais inteligível, pode-se preceder o número de linha com a palavra chave \textit{line}. Indicações de linhas negativas significam que nenhuma linha deve ser destacada.
Logo após o número de linha, deve vir o comando ou bloco de comandos a ser executado. Para agrupar comandos em bloco, deve-se colocá-los entre chaves.
Portanto, um passo do Tira-Teima possui o seguinte formato:

\textbf{[line] <número da linha> <comando>}

ou

\textbf{[line] <número da linha> \{<comando> [<comando> ...]\}}

E um roteiro do Tira-Teima corresponde à um conjunto de passos:

\textbf{<passo> [<passo> …]}

\subsection{Comandos}

\subsubsection{Comando Não Faz Nada}

Para apenas destacar a linha, sem que haja alteração na interface do Tira-Teima, basta colocar um ponto-e-vírgula logo depois da indicação de linha:

\textbf{[line] <número da linha>;}

\subsubsection{Declaração de Variáveis}

A noção de variável no Tira-Teima é a mesma que a de qualquer linguagem de programação imperativa. Ao encontrar uma declaração de variável, o Tira-Teima criará um objeto gráfico para representá-la. Seguem abaixo as regras para declarar variáveis.

\paragraph{Variáveis de Tipos Simples}

Os tipos simples são tipos intrínsecos ao Tira-Teima e estão listados na Tabela \ref{tab:tipos}.

\begin{table}[h]
\begin{center}
\begin{tabular}{| c | c |}
\hline
\textbf{Tipo} & \textbf{Descrição} \\
\hline
\hline
\textit{int} & Valores inteiros com sinal, equivalente ao tipo \textit{int} em Java. \\
\textit{real} & Valores reais, equivalente ao tipo \textit{double} em Java.\\
\textit{string} & Seqüências de caracteres, equivalente ao tipo \textit{String} em Java. \\
\textit{char} & Caracteres, equivalente ao tipo \textit{char} em Java. \\
\textit{boolean} & Valores booleanos \textit{true} e \textit{false}, equivalente ao tipo \textit{boolean} em Java\\
\textit{pointer} & Pode receber null, é meramente ilustrativa.\\
\hline
\end{tabular}
\end{center}

\caption{Tipos básicos do Tira-Teima.}
\label{tab:tipos}
\end{table}


Para declarar uma variável no Tira-Teima defina os seguintes parâmetros:

\textbf{<tipo> <nome da variável> color(<cor em rgb>) size(<largura>,<altura>) position(<x>,<y>);}

Por exemplo:

\textbf{int X color(255,0,0) size(120,30) position(40,40);}
%TODO indicar qual o numero da secao de funcoes

Para criar várias variáveis ao mesmo tempo, basta separar os nomes das variáveis com vírgula:

\textbf{<tipo> var1, var2, var3;}

Não podem existir duas variáveis com mesmo nome em um mesmo escopo. A definição de escopo é vista na Seção de funções. Embora não seja obrigatório informar a cor, o tamanho e a posição, isso é recomendável para que o programa fique apresentado como se espera.

\paragraph{Tipos Definidos Pelo Usuário}

Como em qualquer outra linguagem, um tipo definido pelo usuário é um conjunto de campos que forma um registro. A sintaxe para definição de tipos é a seguinte:

\\
\textbf{record} <nome do novo tipo> \{

<tipo1> <campo1>; 

<tipo2> <campo2>; 

...

 <tipoN> <campoN>;

\}

Por exemplo, pode-se definir o tipo Pessoa da seguinte forma:

\textbf{record} Pessoa \{ 

string nome; 

int idade;

\}

As regras de criação de variáveis também valem para os campos de um registro, ou seja,
o tipo de um campo pode ser outro registro, desde que ele tenha sido declarado previamente.
Um campo pode ser também um vetor ou uma matriz, basta que o índice seja especificado.
Adicionalmente, pode-se declarar vários campos ao mesmo tempo, conforme mostrado abaixo: 

\textbf{<tipo> <campo1>, <campo2>, ...;}

Em geral:

\\
\textbf{record} <nome > \{

<tipo ><nome>[[<índice>[,<índice>]][,<nome>[[<índice>[,<índice>]] …];

[<tipo ><nome>[[<índice>[,<índice>]][,<nome>[[<índice>[,<índice>]] …]; …]

\}

\paragraph{Variáveis de Tipos Definidos Pelo Usuário}

Um tipo definido pelo usuário é um uma estrutura cuja definição é explicada mais a frente. De qualquer forma, um registro é o equivalente a uma struct de C ou um record de Pascal. Portanto, a especificação de um tipo definido pelo usuário possui o seguinte formato:

\textbf{<nome do tipo> <nome da variável>;}

Assumindo que exista um registro chamado \textit{Pessoa}, a criação uma variável do tipo \textit{Pessoa} seria da seguinte forma:

\textbf{Pessoa <nome da variável>;}

\paragraph{Vetores e Matrizes}

Para criar vetores e matrizes, adicione um índice logo após o nome da variável. Esse índice deve vir entre colchetes, indicando o tamanho do vetor. Por exemplo, para criar um vetor de inteiros com 5 elementos, temos:

\textbf{int meu\_vetor[5];}

Para matrizes, basta colocar dois índices. Exemplo:

\textbf{string matrix[5, 10];}

Para declarar mais de um vetor ou matriz com o mesmo tipo, segue a regra (onde tipo pode ser um tipo básico ou o nome de um tipo definido pelo usuário):

\textbf{<tipo ><nome>[[<índice>[,<índice>]][,<nome>[[<índice>[,<índice>]] …];}

\subsubsection{Atribuição de Valores a Variáveis}

Para atribuir um valor a uma variável temos:

\textbf{<variável> = <expressão>;}

Essa expressão utiliza os operadores descritos na seção operadores da expressão:

\begin{itemize}
\item se a variável v é um registro, então v.<um campo de v> também é uma variável válida;
\item se a variável v é um vetor ou matriz, então v[<índice de um elemento de v>] também é uma variável válida.
\end{itemize}

Também é preciso garantir que o valor retornado pela expressão seja do mesmo tipo de v. Não é possível atribuir uma \textit{string} para um caractere ou vice-versa, ou uma \textit{string} para um inteiro ou real. A exceção é a atribuição de um número inteiro para um real.

Em geral:

\textbf{<nome>[< <índice> ou .<nome> > …] = <expressao>;}

O valor é atribuído sempre à variável no escopo o mais local possível. Essa questão é tratada na Seção de funções.

\subsubsection{Remoção de Variáveis}

Para remover uma variável utilize o seguinte comando:

\textbf{removeVariable(<variável>);}

Isso pode ser utilizado para simular a liberação de memória, como no caso da linguagem C, que utiliza o \textit{free(var)} para desalocar o espaço de memória ocupado por uma variável.

\subsubsection{Ocultando o nome da variável}

Para representar comandos de alocação dinâmica de memória é necessária a criação de variáveis sem nome. Dessa maneira, para criar uma variável sem nome basta fazer usar a opção: 

\textbf{showName(<valor booleano>)}

 ao declarar uma variável.

Dessa maneira, declara-se uma variável sem nome com o seguinte comando:

\textbf{<tipo> <identificador> color(<cor em RGB>) size<largura>,<altura>) \\ position(<x>,<y>) showName(<verdadeiro ou falso>);}

No exemplo abaixo temos a declaração de uma variável em que na interface do Tira-Teima não apareceria a palavra ``numero''. No entanto, para fins de atribuição de valores, o Tira-Teima reconheceria essa palavra como um identificador. 

\textbf{int numero color(150,150,150) size(80,30) position(350,90) showName(false);}

Um exemplo de código para alocação de desalocação de memória seria conforme mostrado abaixo. Neste exemplo, é criado um número inteiro sem nome, que representa o espaço alocado para o ponteiro p1. %TODO colocar figura ilustrando
\\

\hline
3;

4 pointer p1 color(150,150,255) size(50,20) position (363,170);

5 {p1 point(388,130); int numero color(150,150,150) size(80,30) position(350,90) showName(false);}

6 numero = 10;

7 writeLine(``10'');

8 removeVariable(numero);

9 p1 = null;

10;
\hline

\subsubsection{Trabalhando com o Console}

O console do Tira-Teima simula o terminal do sistema operacional. Permite a leitura de entradas do usuário e apresenta saídas do programa. Para as entradas do usuário, possui os comandos \textit{read} para leitura e \textit{readLine} para leitura com quebra de linha. Em geral:

\textbf{read([<variável ou constante>] [,<variável ou constante>  …]);}

e

\textbf{readLine([<variável ou constante>] [,<variável ou constante>  …]);}

Para as saídas do programa, possui os comandos \textit{write} para escrita e \textit{writeLine} para escrita com quebra de linha. Em geral:

\textbf{write([<variável ou constante>] [,<variável ou constante>  …]);}

e

\textbf{writeLine([<variável ou constante>] [,<variável ou constante>  …]);}

Note que a lista de parâmetros pode ser vazia mas os parênteses são obrigatórios. Para acessar campos de registros ou elementos de vetores ou matrizes, segue-se a mesma regra do ponto e do índice, respectivamente.
%Pode-se também usar o comando writeln com a diferença que esse comando adiciona uma nova linha após escrever os valores.

\subsubsection{Trabalhando com Arquivos}

A manipulação de arquivos do Tira-Teima contém comandos para arquivos texto e binário. %Portanto, os comandos e conceitos a seguir se comportam da mesma maneira que nessa linguagem.
%Note que o suporte a arquivos binários no Tira-Teima foi descontinuado, logo, sempre que o termo arquivo for usado, ele refere-se a arquivos texto.
 Conforme explicado na Seção \ref{sec:config}, de configuração e execução, se um arquivo for aberto para leitura, ele deve existir fisicamente e estar presente no mesmo diretório do Tira-Teima.

\paragraph{Declarando um Arquivo (Simbólico)}

Para declarar um arquivo texto, siga a mesma sintaxe da declaração de variáveis usando o tipo \textit{textFile}.
Existem duas restrições para variáveis do tipo arquivo: não podem existir vetores ou matrizes de arquivos e arquivos não podem ser campos de vetores.
Portanto em geral:

\textbf{textFile <arq1>, <arq2>, ..., <arqN>;}

ou, formalmente:

\textbf{textFile <nome>[, <nome> …];}

Para arquivos binários basta utilizar o tipo \textit{binFile} no lugar de \textit{textFile}.


\paragraph{Abrindo um Arquivo}

Para abrir um arquivo de texto, use o comando \textit{open}:

\textbf{open(<nome>);}

O nome refere-se à variável \textit{textFile}, ou seja, ao arquivo simbólico. Para a leitura de arquivo,
deve-se associá-lo à um arquivo físico que esteja no mesmo diretório do programa passado como
parâmetro. Os arquivos são abertos para escrita e leitura. Quando abertos eles tornam-se
arquivos virtuais no Tira-Teima, caso o arquivo não exista fisicamente então será aberto com o
conteúdo vazio. Para arquivos binários utiliza-se o comando \textit{binOpen}.

%\paragraph{Abrindo um Arquivo para Escrita}
%
%Para abrir um arquivo exclusivamente para escrita, utilize o comando \textit{rewrite}:
%
%\textbf{rewrite(<nome>);}
%
%O nome se refere à variável \textit{textFile}, ou seja, ao arquivo simbólico. Para que seja aberto, o arquivo simbólico é associado a um arquivo que não precisa existir. Os arquivos abertos para escrita só existem em memória e seus dados não são preservados após a execução.

\paragraph{Fechando um Arquivo}

Para fechar um arquivo, utilize o comando \textit{close}:

\textbf{close(<nome>);}

O nome refere-se à variável \textit{textFile}, ou seja, ao arquivo simbólico. O arquivo simbólico permanece associado ao arquivo físico depois de fechado.

\paragraph{Lendo e Escrevendo em Arquivos}

Para se escrever em um arquivo texto, também usa-se o comando \textit{write}. No entanto, o primeiro parâmetro é o nome do arquivo simbólico. Portanto:

\textbf{write(<nome>, [<variável ou constante>] [,<variável ou constante>  …]);}

O comando \textit{writeLine} também funciona da mesma forma para arquivos.

Para se ler dados de arquivos, deve-se usar os comandos \textit{read} e \textit{readLine}. Devido à ausência de \textit{strings} de tamanho fixo no Tira-Teima, esses comandos têm uma sintaxe levemente diferente de \textit{write} e \textit{writeLine}. Devem se obedecidas as seguintes regras:

\begin{itemize}
\item Só pode ser lida uma variável por vez. Dado o tipo da variável, o Tira-Teima vai inferir o tipo de dado a ser lido. 
\item Só podem ser lidas variáveis (que incluem campos de registros e elementos de vetores e matrizes) dos tipos básicos, à exceção de \textit{boolean}, ou seja, \textit{int}, \textit{real}, \textit{string} e \textit{char}.
\item Para o tipo \textit{string}, pode ser passado um parâmetro adicional, definindo o número de caracteres que devem ser lidos. Se esse parâmetro não for informado, será lido até a primeira quebra de linha.
\item Para os tipos \textit{int} e \textit{real}, todos os espaços em branco (inclusive quebras de linha) antes do primeiro dígito serão ignorados.
\end{itemize}

Em geral:

\textbf{read(<nome arq>, <nome var>[, <número de caracteres, se var for string>]);}
 
O comando \textit{readLine} também lê apenas uma variável. No entanto, após ler os dados, ele vai ignorar todos os caracteres até a primeira quebra de linha que encontrar. Portanto,

\textbf{readLine(<nome arq>, <variável string>, <número de caracteres X>);}

irá ler X caracteres e ignorar até o final da linha.

\textbf{readLine(<nome arq>, <variável string>);}

é o mesmo que \textit{read}.

\paragraph{Leitura de um único caractere}
O comando
\textit{getFileC} faz a leitura de apenas um caractere
do arquivo. Foi introduzido principalmente para facilitar a busca pelo o marcador de final de
arquivo EOF na linguagem C. Em geral:

\textbf{getFileC (<nome\_arq>, <veriavel\_char>)}

Exemplo:

\textbf{getFileC (arq1, c)}

Caso não seja mais possível realizar a leitura (ou seja chegou ao final do arquivo), atribui-se
valor nulo à variável e não EOF como em C.

\paragraph{Posicionamento do cursor}

Para posicionar o cursor do arquivo em uma determinada posição utiliza-se o comando
\textit{seekFile}, implementado de forma semelhante ao \textit{fseek} da linguagem C. Em
geral:

\textbf{seekFile (<nome arq>, <variavel ou consante com o valor do offset>, <modo>)}

Modos:
\begin{itemize}
\item SEEK\_SET - do comeco do arquivo;
\item SEEK\_CUR - da posicao atual;
\item SEEK\_END - do final do arquivo.
\end{itemize}
 
Exemplos:

\textbf{seekFile (arq1, 0 , SEEK\_SET);} - leitura a partir do início do arquivo.

\textbf{seekFile (arq1, x , SEEK\_SET);} - leitura a x posições do início do arquivo.

\textbf{seekFile (arq1, -3 , SEEK\_END);} - leitura a partir do antepenúltimo caractere do
arquivo.

\subsubsection{Ponteiros}

O Tira-Teima dá suporte a ponteiros de forma didática, indicando que variável está sendo apontada pelo ponteiro. Entretanto, ele não guarda de fato os endereços das variáveis.
Os ponteiros podem possuir um valor nulo, não inicializado (sujeira de memória) ou podem apontar
para algum endereço em memória. Também pode ser passado como parâmetro para as funções
(Seção Funções e Ponteiros).

\paragraph{Declarando Ponteiros}

Ponteiros são declarados da mesma forma que as demais variáveis.
Por exemplo:

\textbf{pointer p color(255,0,0) size(120,30) position(40,40);}

\paragraph{Atribuindo valores a Ponteiros}


No Tira-Teima o ponteiro apenas pode receber um tipo de valor, que é o valor
null. Quando isso ocorre, a variável, que se inicializa com seu interior
hachurado, passa a ter apenas um ponto no meio (indicação de ponteiro nulo). Para inicializar
um ponteiro como
null temos:

\textbf{p = null;}

Outra funcionalidade suportada pelo Tira-Teima é a de apontar para (referenciar) outra
variável. Isso é representado por meio de uma seta, utilizando-se o comando:

\textbf{<nome ponteiro> point(<X>, <Y>);}

Exemplo:

\textbf{p point(20,30);}

Não é preciso informar o nome da variável apontada, sendo necessário colocar a variável
referenciada na posição apontada pela seta. Ou seja, a seta não aponta automaticamente para
uma variável, isso deve ser feito por quem escreve o roteiro.

Exemplo de roteiro utilizando ponteiros:
\\

\hline
3;

4 int numero color(150,150,150) size(80,30) position(350,90);

5 pointer p color(150,150,255) size(50,20) position(363,170);

6 p = null;

7 p point(388,130);

8 numero = 10;

9 writeLine("10");

10 p = null;

11;

\hline

\subsubsection{Funções}

No Tira-Teima, uma função é representada por uma região em que aparecem as variáveis
presentes dentro do escopo da função.

\paragraph{Declarando Funções}

Para declarar uma função, tendo parâmetros ou não, é necessário incluir
o seguinte comando:

\textbf{function <nome funcao>(<lista de parametros>):<tipo de retorno>\{<lista de
variáveis locais\}}

Exemplos:

\textbf{function foo():void;}

\textbf{function foo(int a color(255,0,0) size(120,30) position(40,40);) : int;}

Pode-se declarar uma lista de variáveis locais à função, como em:

\textbf{function foo(int a color(255,0,0) size(120,30) position(40,40);) : int \{}

\textbf{int b color(255,0,0) size(120,30) position(40,40);}

\textbf{\};}

\\
O parâmetro <nome funcao> é um identificador do nome da função e segue a mesma regra de nomes de variáveis. A lista de parâmetros é uma lista de variáveis que deverá ter um ``;'' após cada variável listada, inclusive a última. O <tipo de retorno> pode ser do mesmo tipo das variáveis. A lista de variáveis locais é uma lista de variáveis que serão inicializadas junto com a função. Observe que a definição da lista de parâmetros e da lista de variáveis locais são opcionais.

\paragraph{Inicializando Funções}

Ao inicializar uma função, um região na interface do Tira-Teima é
reservada com um título contendo a assinatura da função criada (nome, parâmetros, tipo de
retorno).
A partir de então, inicializa-se um novo escopo de variáveis.
Podem haver nomes
iguais aos do fluxo principal que chamará a função. No entanto, variáveis de dentro da função só
serão visíveis enquanto esta estiver sendo simulada pelo Tira-Teima. Para iniciar uma função,
utilize o seguinte comando:

\textbf{start foo();}

No caso de parâmetros:

\textbf{start foo(a,b,c);}

Esses parâmetros já devem estar previamente declarados. Para passagem de parâmetros por
referência, temos:

\textbf{start foo(address a);}

\paragraph{Terminando Funções}

Ao terminar uma função, a região relativa à função desaparece juntamente com as variáveis de seu escopo. Para isso utilize o comando:

\textbf{end;}

\paragraph{Funções e Ponteiros}

Para trabalhar com ponteiros e funções, deve-se combinar vários comandos. Uma função pode receber e retornar ponteiros, além poder trabalhar com ponteiros
internamente. Adicionalmente, ponteiros dentro das funções podem referenciar variáveis de fora
da função, inclusive para mostrar como algumas linguagens passam variáveis por referência
usando ponteiros, como C. Para retornar um ponteiro, declara-se na denição da função:

\textbf{function foo():pointer;}

Para receber um ponteiro, deve-se declarar o ponteiro na função normalmente, por exemplo:

\textbf{function foo(pointer p color(255,0,0) size(120,30) position(40,40);):void;}

Ao inicializar a função, pode-se passar um ponteiro diretamente:

\textbf{start foo(pointer pAux);}

ou o que seria o endereço (referência) da variável, como em:

\textbf{function foo(pointer p color(255,0,0) size(120,30) position(40,40);):void;}

\textbf{int a color(255,0,0) size(120,30) position(20,60);}

\textbf{start foo(address a);}

Observe que a função recebe um ponteiro, mas foi iniciada com uma variável do tipo inteiro.
Para que faça sentido didaticamente, é recomendado que se combine a passagem por parâmetro
com outros comandos, de modo a gerar uma visualização mais fiel. Abaixo segue
um exemplo de utilização:
\\
\\
\hline
1 function incrementa(pointer p color(150,150,255) size(50,20) position(20,60);):void;

7;

8 int x color(150,150,150) size(50,20) position(20,20);

9 x = 10;

10;

3 start incrementa(address x); p point(45,30); insertText(``x'') size(12) position(34,10);

4 x = 11;

5 end;

10;

11 writeLine(``11'');

12;

\hline

\\

Observe que ao iniciar a função, também foi apontada uma seta para cima e inserida a
palavra ``x'', representando a variável fora do escopo da função.


\end{document}


